Dify 1.17 升级实测（一）：从工作流平台到 Agent 平台，升级前必须知道的 5 件事

📖 摘要：Dify 1.17.0 把定位从工作流平台转向 Agent 平台——新增三个服务、十七张数据表，同时带来三处 DSL 破坏性变更。本文基于本机 91 个应用、云端 5 个应用的真实升级过程，梳理升级前必须知道的 5 件事：新服务配齐、LLM 节点 DSL 迁移、迭代格式大改、文件访问控制变化、模型三段式配置。给升级评估和迁移成本一个可量化的答案。

一、实验目的：升级 1.17 前，先回答一个成本问题

Dify 1.17.0 发布后，很多团队的第一反应是：改个镜像 tag，重新拉起来，完事。

我们当时的想法也一样。直到真的动手，才发现这次升级的「破坏面」比想象中大——新增了三个服务、改了三处 DSL 格式、换了一套文件访问控制。如果只改镜像 tag，升级完的应用要么起不来，要么跑不对。

这篇文章不是发布公告的复述，而是两套真实环境（本机 91 应用 + 云端 5 应用）升级全过程的记录：什么变了、哪些东西会坏、升级要多久、怎么验证。适合正在评估「要不要升 1.17」的技术负责人，以及马上要动手的交付工程师。

二、场景设计：两套环境，一次完整的升级对照

升级前先盘点存量，这是评估迁移成本的基础：

两套环境的升级路径略有差异：本机用 git 源码目录切 tag，云端直接切官方 tag。但核心流程一致：备份 → 切换版本 → 补环境变量 → 拉镜像 → 迁移数据库 → 验证。

三、整体架构：1.17 增加了什么

先看架构层面的变化。1.17 的 compose 比 1.16 多了三个服务：

三个新服务的定位：

• agent_backend：Agent 运行时编排——1.17 的 Agent V2 节点（后面单独一篇讲）由它执行，不再在 api 容器内跑
• agent_local_sandbox：工具/代码执行的隔离沙箱（本地模式；还有 E2B 云沙箱可选）
• agent_ssrf_proxy：Agent 工具访问外部 URL 时的 SSRF 防护代理

对应的，数据库新增了 17 张表，集中在 Agent 生态：agents、agent_workspaces、agent_home_snapshots、skills、skill_versions、agent_config_revisions 等——Agent 从「工作流里的一种节点」升级为「平台级的一等公民」，这是 1.17 定位转变的最直接证据。

四、升级前必须知道的 5 件事

这是全文的核心。5 件事 = 5 个升级决策点，每件都直接影响「升级后能不能用」：

① 新服务必须配齐，不能只改镜像 tag

1.16 升 1.17 时，如果沿用旧 compose 只把 api/web 镜像改成 1.17，会发现 Agent 相关能力全部不可用——agent_backend 和 local_sandbox 根本没起。正确做法：用 1.17 的官方 compose 做基准，把本地的个性化修改（端口、ulimits 等）重新合入。我们云端环境有 5 个服务的 ulimits 修改（文件描述符上限修复），重放时逐项核对 docker compose config -q 通过才继续。

② LLM 节点 DSL 有破坏性变更（旧 DSL 导入会报错）

两处必改：

# 1.16 的写法（已废除）

prompt_template:

  - role: user

    text: {enabled: true, jinja: false, value: "你的提示词"}



# 1.17 的写法（text 直接是字符串）

prompt_template:

  - role: user

    text: "你的提示词"

另外 memory 配置新增必填字段：

# 1.16 的写法（1.17 报 Field required）

memory: {enabled: false}



# 1.17 的写法

memory: {enabled: false, window: {enabled: false}}

存量应用如果导出 DSL 再导入，这两处不改直接 400。所有包含 LLM 节点的手工 DSL 都要过一遍。

③ iteration 节点格式大改（旧迭代 DSL 不兼容）

1.17 的迭代节点从「items + output」改成「start_node_id + iterator_selector + output_selector」：

# 1.16 的写法（已废除）

- id: iter_check

  data:

    type: iteration

    items: {value_selector: ["cd_items", "items"]}

    output: iter_result



# 1.17 的写法

- id: iter_check

  data:

    type: iteration

    start_node_id: iter_start

    iterator_selector: ["cd_items", "items"]

    output_selector: ["cd_build", "result"]

同时迭代开始节点的类型从 custom-iteration-start 改成 iteration-start，迭代内节点也不再需要 isInIteration/iteration_id/parentId 标记——范围由 start_node_id 界定。凡是用过迭代/循环的存量应用，DSL 都要迁移。

④ 文件变量与访问控制变了

文件变量的类型白名单从 MIME 类型改成分类枚举：image / document / audio / video / custom（写 image/png 直接 400）。同时，console 上传的文件与 service API 运行时是隔离的——调用方上传文件必须走 POST /v1/files/upload，且文件绑定上传时的应用，换应用要重新上传。

⑤ 模型配置统一三段式

模型配置全面改为插件三段式前缀：langgenius/deepseek/deepseek、langgenius/tongyi/tongyi。环境变量、LLM 节点、Agent 配置里的 provider 都要用这个格式。

五、升级路径：四步走 + 真实耗时

实际升级流程（两套环境都验证过）：

1. 备份：数据库用 pg_dump（热拷不安全），卷直接拷贝（注意 Windows 下符号链接要展开为实文件）；云端备份 1.4G，本机备份 2.9G
2. 切换版本：git 切 1.17.0 tag（detached HEAD 是官方标准态）；本机把个性化 compose 差异存档成 patch 备用
3. 补环境变量：对照官方 .env.example 补齐缺失键——本机补了 21 个键（1.17 新增 DIFY_AGENT_* 系列），云端补 7 个
4. 拉镜像 + 迁移数据库：本机约 40 分钟（4.15G 的 api 镜像是大头，Docker Hub 抖动中断一次重试成功）；云端几分钟（加速器）；flask db upgrade 迁移到新 head

六、运行验证：四步验证全过

升级完不是「能打开界面」就算完，我们做了四步验证：

额外收获：1.16 遗留的「插件列表 404」预存 bug 在 1.17 修复了（plugin_daemon 从 0.6.1 升到 0.6.10-local）——升级后插件 404 计数归零。

云端升级还验证了生产链路：停机约 2 分钟，升级完成后企微/钉钉/飞书三平台自动重连，冒烟测试通过。

七、实战坑：升级过程中踩到的 6 个坑

八、升级决策建议

回到开头的问题：要不要升 1.17？

• 要升：需要 Agent 能力（Agent V2 节点、技能包）、迭代内人工审批、多模态直传——这些是 1.17 才有的
• 可以缓：存量应用大量使用自定义 DSL 迭代节点 + LLM 节点的，先做 DSL 迁移评估（5 件事里的 ②③ 影响最大）
• 升级成本：单环境约 1-2 小时（不含备份恢复），破坏性变更集中在 DSL 层，应用数据不受影响

一句话总结：1.17 的升级成本不在镜像，在 DSL——提前把存量 DSL 过一遍，升级就是一次平滑迁移。

实验文档与源码获取

本文系列基于 dify108 批次 5 个实验（LLM 环境变量 / Agent V2 / Skill 管理 / 迭代内 HITL / 多模态直传），实验文档与 DSL 已归档：

• dify-108 实验工作区（实验记录 + 全部 DSL）
• 本系列后续篇目：二、Agent V2 节点与技能包实测 ｜ 三、循环内人工审批与图片直传实测

本文基于 Dify 1.17.0 + Hermes Agent v0.21.0 实测，配置在不同版本间可能变化，使用前请确认版本。AI 参与创作声明：本文由 AI 辅助写作，内容基于作者真实实测记录。